Ham Radio 2000 #1

home *** CD-ROM | disk | FTP | other *** search

/ Ham Radio 2000 #1 / Ham Radio 2000.iso / ham2000 / packet / terminal / simptr23 / simp.doc < prev next >

Wrap

Text File | 1996-02-04 | 82.6 KB | 2,035 lines

SimpTerm - A Simple Amateur Radio Communications Program, Version 2.3 Jim Lynch February 4, 1996 Contents 1 Introduction 2 2 Quick start 4 3 Display description 5 3.1 Receive window . . . . . . . . . . . . . . . . . . .5 3.2 Status line . . . . . . . . . . . . . . . . . . . . .5 3.3 Transmit window . . . . . . . . . . . . . . . . . . 5 4 The Initialization file 5 4.1 Keyboard assignments . . . . . . . . . . . . . . . .5 4.1.1 Special characters and variable substitutions 6 4.1.2 Keyboard macros . . . . . . . . . . . . . . . 8 4.1.3 Assigning files to function keys . . . . . . 9 4.1.4 Assigning functions to function keys . . . . 10 4.2 Definition variables . . . . . . . . . . . . . . . .16 4.3 Color Configuration . . . . . . . . . . . . . . . .25 4.4 Command line options . . . . . . . . . . . . . . . .25 5 CD-ROM support 27 6 Mouse usage 27 7 Pull-down menu 28 8 Station logbook 28 9 Selective calling feature 29 10 License 29 11 In Case of Trouble 30 1 12 Error messages 31 13 Final notes 32 14 Bugs 33 15 Futures 33 1 Introduction SimpTerm is a simple terminal program designed to be used with almost any tnc or tu on the market. Features of SimpTerm are: o Split window operation. o Macro key definitions. o User customizable Help screen o Most of the non-ascii keys can be used as function keys o Optional scroll back feature on the receive and transmit win- dows o Simple status display in the middle of the screen o Capturing of data to a disk file o Access DOS commands without dropping communications connection o Control of the com port definitions from command line, init file and keyboard. o Works on 8088 as well as 80486 and everything in-between. o Small enough to work well on resource tight platforms, like laptops. o Selcal functions, limited unattended operation. o Times can be in GMT or local time. o A station logging function. o Can be set to send CQ or other message repeatedly o User selectable color scheme o Automatically senses incoming call letters 2 o Support for call lookup using either QRZ or AmSoft CD- ROMs o Pull-down menu access to most functions o A set of "buttons" used to change modes quickly o Support for non-standard IRQ and UART I/O base addresses for COM ports o Function keys and control keys can be assigned to a macro string, cause a file to be uploaded or call a function within the program. o DesqView aware There are loads of programs that are tailored to specific tnc's and there are dozens of good terminal programs that can control any tnc in a "dumb" (that's a technical term) manner. This program is an attempt to provide the average ham with something in-between. It has a lot of features, but not so many as to make use of the program or the tnc hard. It requires you to know the commands of your tnc, but also gives you the flexibility that only direct communications with a tnc can provide. Statistics Author: Jim Lynch Call: K4GVO Address: 128 Carrollwood Dr. Fayetteville, GA 30214 internet address: k4gvo@america.net (preferred) or jwl@cray.com If you write, please enclose a sase. If you don't I reserve the right not to answer. Requirements o IBM PC or clone o DOS 3.1 or greater o CGA, EGA, VGA or better monitor and graphics card o 1 Mb disk o 512K memory o 8088 or better CPU o TNC connected to a COM port 3 Development SimpTerm was developed with: o Turbo C 2.0 o C/Windows Toolchest, from Mix Software o EnCom 1.50 COM library, from EnQue Software The orignal development effort was on a Toshiba T1000SE, and it runs on my 386sx with a VGA color monitor as well as a 486SLC- 66. 2 Quick start Edit the simp.ini file and change the line that looks like: MYCALL NONE to include your call rather than NONE. Make sure the line that starts with "COM" looks ok for your setup. If you have any prob- lems understanding that line, see the discussion on the COM di- rective later in this document. Now execute the program. You will see an intro screen followed shortly by a message instructing you to hit any key. Do so and you should see the screen split into two windows with a status line between them. If you press enter, you will should see the prompt from your TNC appear in the top window. If you don't, then a number of things could be wrong. See the trouble shooting section of the manual for additional help. Press the F1 key. You should see a new window appear listing some of the function keys that are currently assigned to functions and what those functions do. Press any key to close the help win- dow. Press the F3 key. You should have a screen that displays small windows of different colors with a number assigned to each. Also you should see a menu near the bottom center of the screen. The menu is used to change the colors of the receive, transmit, status and logging screens. See the section on configuration for details. Press ESC to return the normal display if you like the default colors. Press the F10 key. This will bring up a drop-down menu that will allow you to access many of the functions without remembering what function keys were assigned. Press the ESC key to close the menu. Enter your tnc commands as you would normally do with a dumb terminal. If you have the echo turned on (in your tnc), you will see the commands as you type on both screens. 4 Take a look at the simp.ini file and read the section on the initialization file details. You should be able to customize this file fairly easily. 3 Display description There are three displays on the main screen. These are the trans- mit, receive and status windows. 3.1 Receive window This is the top window. Data coming back from the RS-232 port will be displayed here. That is usually the output from the other station. If you have the echo turned on you will also see the com- mands that you typed. 3.2 Status line The screen is divided into two separate windows with a status line between them. This status line contains information about the current configuration of SimpTerm, the status of the selcal features and other interesting information. 3.3 Transmit window This is the bottom window. It displays what you are typing and some of the error messages reported by SimpTerm. 4 The Initialization file The initialize file (init file) is used to load the keyboard macros, assign keys to files, specify initial com port settings, specify a "preload" file for customizing your tnc each time you start SimpTerm and to define a number of other options. The default init file name is simp.ini. This file must be in the directory from which you started SimpTerm. 4.1 Keyboard assignments Keys can be assigned to macros, functions or be used to initiate file uploads. A full listing of the keys that can be assigned are described in the keys.doc file found in this distribution. They take the form of: 5 KEY_{modifier_}keyname The modifier may or may not be necessary, hence the curly braces, meaning the stuff inside the braces isn't necessary, but might be important. The modifier is one of the following: SHIFT (or SHFT in one case) designates the key must be de- pressed with the shift key held down. CTRL designates the key must be depressed with the control key held down. ALT designates the key must be depressed with the alt key held down. A few examples of valid keys are: o KEY_ALT-X o KEY_CTRL_P o KEY_F10 o KEY_SHFT_TAB (this is the only SHFT, the rest are SHIFT) o KEY_SHIFT_F4 4.1.1 Special characters and variable substitutions Most of the strings that are defined in the initialization file can contain special character sequences that permit customization of those strings and insertion of non-ascii control codes. A simple example would be to assign a signature string to a function key that would be used at the end of each transmission. If you wanted to send something like: KD4RQN de K4GVO 12-DEC94 14:22 K You might have the following in your initialization file. MYCALL K4GVO KEY_ALT_F10 ^M%C de %L %D K^M Anytime you press ALT-F10 you would send the signature line with the correct date and time. The following paragraphs detail the special character sequences. 6 Forming control characters Control characters are formed by a commonly used notation where the caret precedes a character to indicate the control code should be sent and not the character itself. E. g. ^m carriage return (enter) ^j line feed ^d Control-d ^@ Null (0) ^^ caret Some of the control characters can be specified via the C lan- guage backslash escape notation. These are the only ones allowed. \t tab \n linefeed (new line) \r return \\ backslash Defining dates and times Also included are a few time and date functions that can be specified by a %c notation, where c is one of the following: D The date and time in the form dd-MMMyy hh:mm t The time in the form hh:mm d The date in the form dd-MMMyy Y The year in the form yy M The month in the form MM A The day of the month in the form dd H The hour in the form hh m The minute in the form mm S The second in the form ss Where: 7 dd is the day of the month, MMM is the 3 Character abbreviation of the month yy is the 2 digit year hh is the hour mm is the minute MM is the month (1-12) Other substitutions If you have used the mouse or the call menu to select an active call that is currently being displayed on the status line (column 2), then you can use that call in a string with the %C substitution. See the example at the begining of this section. A %L will be replaced with the value of the MYCALL variable. See the example at the begining of this section. 4.1.2 Keyboard macros Keyboard macros are strings that can be assigned to many of the keys on your keyboard. This lets you assign frequently used char- acter strings to a single key to save keystrokes. For instance, you might want to assign your call to the F1 key and your name to the F2 key and your QTH to the F3 key. That way when you were talking to someone (with your fingers, that is) you would just type "Hi, this is <F1>, <F2> in <F3>" and your computer would fill in the right stuff. <F1> in the above example means that you hit the F1 key, not that you typed the string "<F1>". Bear with me you old timers, I want to make sure the newcomers don't give up on us. To define a macro you need to place the key name (yes, it must be in upper case) in column one, followed by a space, followed by the macro replacement string. A simple example based on the earlier discussion would be: o KEY_F1 K4GVO o KEY_F2 Jim o KEY_F3 Fayetteville, GA Now when you press <F1> <F2> <F3> K4GVO JIM Fayetteville, GA 8 will get sent to the tnc. I hope you were connected to someone, 'cause sending that garbage to the tnc in command mode won't be very productive. The maximum length of a string that can be assigned to a key is 511 characters. You can continue the string on the next line by placing a backslash (\) character at the very end of a line and continuing with the definition on the next line. Be careful not to add a space after the \ because you won't be able to see it and the program will think the next line is a new macro definition. Note that there will be no line breaks sent at the end of the line. Example: KEY_ALT_C cq cq cq cq cq cq de k4gvo \ cq cq cq cq cq cq de k4gvo \ cq cq cq de k4gvo k This is an example of a complete definition. Note that the first two lines have the backslash but the last one doesn't. This would be ok for a cw call, but you probably want to be able to insert a new line occasionally for rtty, amtor or packet work. You can insert any control character, including a carriage return (that is what you normally send when you hit the enter key). Let's try the above example with the addition of a carriage return. Example: KEY_ALT_C cq cq cq cq cq cq de k4gvo^M\ cq cq cq cq cq cq de k4gvo^M\ cq cq cq de k4gvo k^M Now we have a reasonably constructed macro that won't offend the station on the other end. A control character is formed by preceding a letter with a caret as shown above. The control characters ctrl-a through ctrl-z are formed as ^A through ^Z. If you want to include the caret as a character to be send, use a double caret (^^). Since there is no such thing as a control-caret, the program will know to send a single caret. You can also specify other special characters and strings. See the section on selective call reply strings for an expanded set of options within the macro string. 4.1.3 Assigning files to function keys A function key can be assigned to a file by preceding the key name with a ampersand (@). The name of the file follows the key name. Hence: 9 @KEY_ALT_U mydefs.txt @KEY_HOME c:\bob\mydefs.txt are valid definitions. When the specified key is depressed, the file is uploaded to the tnc. This means that the contents of the file are sent to the tnc. This is handy for defining a set of parameters to customize your tnc for a specific mode of operation. You could use the macros to do this, but they are limited to only 511 characters. Another use for this is the "brag tape" (the word tape left over from when we used paper tape on the old *eletype machines). You could put a description of your station, location, personal information on a file and by hitting a single key, you can send it to the other station. 4.1.4 Assigning functions to function keys That sounds like a redundant statement doesn't it? It's not really. There are over thiry functions available that can be assigned to function keys. These are: auto start an automatic send loop baudup increment the communications baud rate bauddown decrement the communications baud rate confcom bring up a menu for com parameter selection config configure the colors of the various parts of the screen dispbut display a user configurable menu (See BUTTON) dos jump to dos getcall display a menu of the calls that have been heard help display the help screen keybrcl reload a input buffer logit brings up a data entry form for the station log macro assign a macro to a key on the fly menu display a pull-down menu of all of the above functions quit exit the program. Not a bad function to have. reset reset the communications port rforward scroll the receive window forward one page rforward1 scroll the receive window forward one line rback scroll the receive window back one page rback1 scroll the receive window back one line 10 rlarger make the receive window one line larger rsmaller make the receive window one line smaller savebuf save the receive buffer in a file status print status of selcal tkeybuf toggle storing a input buffer togsel toggle looking for selcal strings togcap toggle logging of the incoming data. upload upload a file, prompts for name xback scroll the transmit window back one page xback1 scroll the transmit window back one line xforward scroll the transmit window forward one page xforward1 scroll the transmit window forward one line The logit function displays the station logging screen. Refer to the station logbook section of the manual for details. The togcap function will either ask for the name of a capture file to start saving data to or close that file if capturing had already been started by a previous call to togcap. The default capture file name is simp.cap. You may override that name by typing in a new name over top of the simp.cap entry. While you are capturing, the phrase "Log on" is displayed on the status line. When you are not capturing, the status lines displays "Log off". Capture is done in text mode which does not pass special characters transparently. If you wish to capture the data in transparent mode you should put a BINARYCAP statement in your .ini file. The help function is a rather simple one. It just opens a window on the screen and dumps the contents of the help file into the window. If the help file is too long, the top part of the screen is scrolled off into never never land. Using a text editor of your choice you may edit this file as you see fit. The default help file is named simp.hlp, but you can tell SimpTerm to use another file via the HELP customization option in the init file. See the init file section for details. Also the full text of this document is available under the Help pull-down menu. The getcall brings up a menu that lets you select a call from a list of recently heard calls. After selection the other call will be dis- played on the status line. If you send a macro string that contains the special character string, %C, this call will be substituted for it. You also can select a call moving the mouse cursor to the first letter of the call and pressing and releasing the left mouse button. To clear the status line, just move the mouse to an empty part of 11 the screen and depress the left button. You don't have to clear the field before selecting a new call however. The lookup function will attempt to find an entry matching the call that is displayed at column 2 of the status bar in a CD- ROM database. The call displayed on the status bar was either as a result of clicking on the first letter of the call with the left mouse button or from invoking the getcall function. Use of this function requires that either the QRZ or AMSOFT parameter be used to specify the path to the CD-ROM drive and the CD present. The dos function brings up a second copy of the command processor. This allows you to execute commands just as if you had exited the program, but the program is still in memory and waiting for you to finish. After you have finished with dos and want to return to SimpTerm, just enter "exit". That will bring you back to SimpTerm where you left off. DON'T type simp again! The communications buffer can hold 2048 characters. That is about one screenful. If you stay away too long, you may lose data. Be careful. There are 8 scrolling functions. These are: rforward, rforward1, rback, rback1, xforward, xforward1, xback xback1 The rforward and xforward functions cause the receive or transmit window to scroll forward one page. The rforward1 and xforward1 functions cause the receive or transmit screens to scroll forward one line. The rback, rback1, xback and xback1 functions perform the reverse operations respectively. The baudup function will increase the baud rate one step. It will cycle through the following baud rates, 300, 1200 2400, 4800 and 9600 in a circular manner. If you must use other rates, you will have to set them via the COM input line in the init file or use the confcom function. The bauddown function will decrease the baud rate one step. It will cycle through the same baud rates as described in the pre- vious paragraph. The rsmaller function will reduce the size of the receive window by one line. This has the effect of moving the status line up one line and increasing the size of the transmit window by one line. The rlarger function has the reverse effect. You cannot reduce either window below 3 lines high. The menu function is used to bring up the pull-down menu. See the section on the pull-down menu for more information. The macro function is used to define a macro and assign it to 12 a key without leaving the program. You are first asked to press a key. This is the key to which the macro will be defined. I suggest you don't use a printable key, like a letter or a number, but that is a legal key. You can use this to assign macros to keys that aren't on the list of valid keys as long as the program recognizes that a key has been pressed. If the selected key already has a string assigned to it, you will be able to edit that string with some limitations. The edit screen is not a fully functional editor. It is still under development. If the string is longer than 77 characters it will be truncated to 77 characters and they will be dislayed on the first line of the edit screen. You will not be able to position the cursor in the middle of a string and press enter to insert a return in the string. The cursor will simply move to the next line. All of the lines of the edit window will be concatenated into a single string, so if you want carriage returns to be sent to the tnc, remember to use one of the special characters, ^m or \r. When you are finished editing the string, press the ESC key. The string will be saved. There is no way to cancel the operation and return the key to it's original function after you have selected a key, but if you press enter when it asks for the key, it won't bring up the edit window. The auto function starts an automatic transmit loop. It was intended to provide a way for the user to send cq periodically but could be used for other things. Here is how to implement it. First assign the auto function to a key, !KEY_ALT_A auto Then assign a macro to another key with the message/cq/call that you want repeated periodically. KEY_ALT_C ^Mx^M\ cq cq cq cq cq cq de k4gvo^M\ cq cq cq cq cq cq de k4gvo^M\ cq cq cq de k4gvo at %t k^M^M^D Now include a loop time via AUTOTIME 120 When you run the program and press the ALT-A key, which invokes the auto function, you will be prompted to enter the key that you want executed. If, in this case, you want to send cq, you would merely press the ALT-C key. If you decided that the 120 seconds was too long to wait, you could press the ENTER key and 13 you would be prompted for a different time delay. If you want to abort the auto function press the space bar. Let's say you pressed the ALT-C key. Your transmitter will come on, send the cq and turn off. 120 seconds after it started transmitting, it will do the same thing. And 120 seconds later and ... Remember that the time is from the beginning of the trans- mission to the beginning of the next transmission. If the time is shorter than the time to transmit, there won't be any delay and the program will transmit forever, unless you stop it. If you get tired of calling, or receive a reply, you can stop the loop by pressing any key. If the program is transmitting, it will continue until it is done and then terminate. While you are in automatic operation you will see a capital letter A in colum 2 of the status line to remind you. In the above example above I showed a working sample for a PK-232. On the PK-232 the letter X turns the transmitter on in RTTY mode and the control-D (^D) turns it off after emptying the buffer. If you are using another model of TNC, you may have to substitute other character sequences for these. Some of the TNCs have a "preload transmit buffer" function that allows you to type-ahead while the other station is sending. Unfortunately, when you send a character to the TNC it blocks the incoming characters until you press a ENTER key. If you are a slow typist, this might cause multiple lines to back up and you might not see that he has turned it over to you. A feature that buffers up your key strokes in the program can be used to alleviate that situtation. The tkeybuf function toggles saving key strokes in a buffer until a specific key is pressed, normally the ENTER key, but it can be assigned to most any function or control key. When you hit the specific key, which is assigned via the SENDKEY variable in the init file, the saved keystrokes are sent to the TNC. You can save up to 2047 key strokes before you send them. That is more than a full 80 by 25 screen full, so should be sufficient for most applications. When SimpTerm is buffering keystrokes, a letter K will be displayed in column 2 of the status line. If the SENDKEY key is the ENTER key, then it is passed along with the buffer, but if it is something else, it is not sent, so don't assign a key to SENDKEY that you want to be able to send. If you want to reload the buffer with the data you just typed in and then sent to the TNC only to discover that you were in command mode rather than type-ahead, you can press the key associated with the keybrcl function. Since you also probably want to put the TNC in type-ahead mode, you will want to hit the key associated with the tkeybuf function first. Then enter the type-ahead command. Then put it back in buffered mode with another tkeybuf function key and then use the keybrcl function. 14 I know it sound complicated, but it sure is better than retyping all that stuff you just lost. For example if the SENDKEY variable looks like: SENDKEY KEY_ENTER You can type what you want without interrupting the output from the TNC until you press the ENTER key. At that time all of the keystrokes are sent to the TNC. The upload function lets you upload any file to the tnc. You will be prompted for the file name. Normally the upload will be done in text mode, which eliminates some control characters. If you want to upload files in binary or transparent mode, include a BINARYLOAD statement in the .ini file. The confcom function brings up a menu screen with radio buttons to use to configure the com port. You may find it isn't worth much unless you have a mouse. To assign a function key to one of these functions, precede the definition by an exclamation point (!). E. g. !KEY_ALT_X quit !KEY_CTRL_L togcap !KEY_ALT_H help !KEY_F10 togsel !KEY_ALT_S status !KEY_ALT_J dos (Jump to dos) The simp.ini file included in the distribution assigns the page- down and pageup keys to the rforward and rback functions respec- tively. Also the up arrow and down arrow keys are assigned to the rback1 and rforward1 functions. Just in case you don't have the quit function assigned to a key, the END key has been permanently bound to the quit function. So you don't accidently hit it and drop out of the program, the end key must be pressed twice in succession to end the program. You can't assign the KEY_END key to anything else. The program won't complain if you try, but it just won't work the way you think it should. There are a few other keys that are special. KEY_BKSP and KEY_CTRL_H are intra-line edit functions and cannot be reassigned. 15 KEY_ENTER can't be reassigned either, obviously. 4.2 Definition variables You can set a number of configuration options by defining variables in the initialization file. This section discusses them. Comment lines If the program finds a # (pound) sign in the first column of a line in the init file, it will stop processing that line. This is the way to comment your init file. Also any of the options described below that have a fixed format will allow comments following all of the permitted arguments. If an option has a variable number of arguments, you can't put a comment on that line. E. g. # this is a valid comment mid 15 # this is ok also. COM port definition option The COM port parameters must be set to match your tnc. If you don't know what speed, word size, etc. that your tnc is using, consult the manual that came with the tnc. A lot of the packet tnc's around have an autobaud detect feature. When you power them up for the first time they wait until you type an asterisk and then they can determine the operating parameters you are using. If you have both a COM option line in your init file and a command line com option then the command line option will be used. This way the command line can be used to override the init file if desired. If you don't tell SimpTerm what parameters to use it will default to: use COM1 2400 bits per second (baud) 8 data bits No parity 1 stop bit. If you include the line, COM1 4800,7,E,1 it will change the COM1 port to work with: 16 4800 bits per second (baud) 7 data bits even parity 1 stop bit. See the section on command line options for the full set of op- tions for each of these parameter fields. There must be at least 4 fields. The COM? line in the initial file requires a SPACE imme- diately after the COM? field. The command line version of this command uses a COMMA between these fields. Try not to get these confused. Of course, if you have your tnc connected to one of the other com ports(like 3), you will want to use a line that looks like: COM3 9600,8,N,1 instead. Examples: COM4 1200,7,N,1,5,0x3E8 COM1 19200,8,N,1 FLOW control specification There are three options for flow control. You may use RTS/CTS, XON/XOFF or no flow control. Specify: FLOW RTS FLOW XOFF FLOW NONE to select one of the three. Default is FLOW RTS. HELP file specification The default HELP file name may be overridden by including the HELP configuration line in the init file. This is simply the key word HELP followed by a file name. When you invoke the help function, the contents of this file are displayed on the screen. You may modify this file for your own purposes. See the section on the help function. The default name for the help file is simp.hlp. 17 MID screen layout One of the feature of SimpTerm is that is has a split screen. This allows you to have a "transmit" window that displays what you are typing along with informative messages from the program and a "receive" window that displays the data coming back from your tnc. The size of the windows is determined by the mid command line option. This value should be between 4 and 20. A value of 15 will give you a 15 line transmit window and a 9 line receive window. If you specify a value for MID out side of this range a default will be chosen for you. DEL_EQ_BKSP specification If you include this definition in your initial file the delete key will work just like the backspace key. If you are used to using the delete key rather than the backspace key, you will want use this keyword. NODV disable DesqView sense The inclusion of the NODV line in the .ini file will tell SimpTerm to act as if DesqView was not loaded. Normally SimpTerm will check for the presence of DesqView and yield to the multi-tasking kernel periodically. If you include NODV SimpTerm will not yield. Use of this parameter is not recommended for normal operation. PRELOAD file specification There is an option available that lets you send a file to the tnc before control is turned over to you at the keyboard. The PRELOAD option line specifies the name of this file. It follows the same form as the HELP file spec. This option may be used to force certain operating parameters when starting up SimpTerm. One use of this feature would be to keep different init files each with a different PRELOAD file. One PRELOAD file might set the tnc to work hf, while another might specify vhf. If you have two hams that use the same equipment, you might want each to have his/her own custom PRELOAD file to change, at least, the call letters. The PRELOAD file may contain the special format characters so you could have a line that looked like: DAYTIME %Y%M%A%H%m and it would set the date and time on your TNC, if it conformed to the TNC-2 standard. 18 POSTLOAD file specification This option names a file that will be uploaded to the tnc at exit time. If you use this option to reset some parameters on your TNC, you should precede the parameters with your escape character to be sure that you are at a command prompt. The POSTLOAD file is scanned for the special format characters. NOSCROLLBAR specification Use this parameter in your .ini file to turn off the scroll bar. This will give you another column on your screen. SCROLLLINES count specification This can be set to a number not to exceed 409. It is used to specify the number of scrolllines in each of the window buffers. I don't know what would happen if you tried to set them to a small number, like 4. The default is 300. Bump it up if you want to scroll back farther and reduce it if you need to recover some memory. CDSWAP specification Use this in your .ini file to force SimpTerm to make more mem- ory available for the CD-ROM database access by swapping. It will cause the access to run slower than normal so don't use it unless you are getting an indication that you have run out of memory while accessing a CD-ROM. DEBUG specification To cause the last key character code to be displayed at the end of the status line, include: DEBUG KEYS in your initial file. TIMELINE display specification You can tell SimpTerm to display the date and time on the status line by including this option in your initial file. This line is searched for the special format characters before being displayed, so a line that looks like: TIMELINE %A-%M-%Y %H:%m:%S in the initial file will cause the status line to display: 25-12-93 12:05:00 19 At 5 minutes past noon on Christmas, 1993, if you're lucky enough to be able to get on the air on Christmas. AUTOTIME time specification AUTOTIME is used in conjunction with the auto function to implement a semi-automated station operation, like a "cq" loop. The AUTOTIME line specifies the number of seconds between loop starts. See the section on the auto function for details. SELFILE file specification This line specifies the name of the file that will receive the selcal messages. The default is "simp.sel". If you want to specify a different file name and/or drive specification put the SELFILE line in the init file. E. g. SELFILE a:\messages The messages that are stored in this file are appended to any previous messages, so you will not lose any previously recorded messages but you might want to look at the size of this file occa- sionally so you don't run yourself out of disk space. GMT time specification line If the program finds this line in the init file, it will attempt to display the times in GMT. Since the time function is only used with selective calling functions, non-selcal users can ignore this option. In order to make these functions work right, you must set your dos clock to your local time and set the environment variable TZ to indicate your local time zone relative to GMT. The format of the TZ variable is: TZ=zzz[+/-]d[d][lll] Where: zzz is a 3 character string representing the name of the current time zone. E. g. CST or EST. [+/- d[d]] is a optionally signed number with 1 or 2 digits. This number is the local time zone's difference from GMT in hours. Positive numbers adjust westward from GMT lll is an optional 3 character field that represents the local time zone daylight savings time. E. g. PDT Environment variables are either set in your autoexec.bat file, or can manually be typed in before you execute the program. Consult your DOS manual for more information. 20 Examples (DOS command line): SET TZ=EST5EDT (New York) SET TZ=CST6 (Indiana, they don't used daylight time, do they?) SET TZ=PST8PDT (Los Angeles) Because of the "new" rules surrounding daylight time, you might find that the time is an hour off during some parts of the year. You might want to keep your dos clock in GMT, or adjust your TZ environment to give you the correct GMT value. SELREPLY reply line When a remote station sends you a specific select, i. e. a request for you to start recording an incoming message, it will expect you to reply immediately with a message so it doesn't waste time sending you a message if your equipment isn't monitoring. This option specifies the reply that you will give in response to the select. The format of this reply line can contain ascii characters, control characters, or special formatting characters. The ascii characters are the normal printable characters (or subset in the case of baudot or amtor). Example: SELREPLY x\r^O^O^O^O^O^Ode K4GVO, %D\r^D Using the PK-232, you can send the "letters" characters with the control-O character, so to make sure that the other station has gotten his transmitter shutoff, you might want to delay your transmission a bit via this method. The "x" character, followed by the carriage return tells the PK-232 to start transmitting. The ctrl-D at the end tells the PK-232 to stop transmitting and resume receiving. RSELCAL selective call string option This line specifies the selcal string(s) that you want to react to. You may specify up to 5 strings. The strings can be delimited by spaces, commas or tabs. The strings can NOT contain any of these characters. Since these strings should probably contain your call or your call and some trailing characters, this shouldn't be a problem. These strings ARE case sensitive. That means that if you are running in a mode that supports upper and lower case, you had better put your selcal in both upper and lower case and hope that the sending station doesn't send mixed case. All strings 21 identified from this set of strings by the program will be replied to with the SELREPLY string. Example: RSELCAL k4gvo K4GVO k4gvo-9 kd4rqn ALLCAL selcal option This option specifies the set of strings that the program will look for to start a "all call" recording. When the program finds a string in this group, it starts recording a message without sending a reply. Other than that, it behaves in exactly the same manner as the RSELCAL option. Example: ALLCAL ANYONELISTENING TOALLOFYOU allcal ENDCALL selcal option Obviously there must be a way to tell the program to stop recording a message and one of these ways is to send a stop string. This option specifies a group of strings that will be used to stop the recording of the incoming message. This the format for these strings is the same as the previous two. Example: ENDCAL NNNN nnnn ZCZC zczc SELMAXT selcal time limit option So that the program doesn't record reams of garbage, a time limit can be specified. This time limit is in seconds and will only record for "n" seconds. If it hasn't received a ENDCAL string by then, it will close the received file. A line will be placed in the file indicating that the recording was terminated because of a timeout. Examples: SELMAXT 300 (record for 5 minutes, maximum) SELMAXT 32000 (record for virtually forever) SELMAXT 12 (record only very short messages!) EXTEND time limit extension string Now it is nice to limit your messages to a specific time limit, but if someone just has to get a long message to you, he(she) will have to send it in chunks. He(she) might not know what you have set your time limit to, so he might have to send it in a lot of little 22 chunks to be sure that he doesn't time out. In order to avoid that problem, the EXTEND option can specify a string that the remote station can send to you to tell you to set your time limit to a different value. The format of the EXTEND option is: EXTEND <string> <newtimelimit> Where: string is a group of characters (not including space and tab) newtimelimit is the absolute maximum that you want someone to set your timelimit to. An example is in order. If you have the following in your init file, EXTEND NEWTIMEX 600 and a remote station sends your selcal string and then (after wait- ing for your reply) sends a line that looks like: NEWTIMEX 300^m (remember the ^m is an enter or end-of-line character) your pro- gram will set your time limit to 300, giving the remote station the opportunity to send you up to 5 minutes worth of data. If he(she) had specified EXTEND NEWTX 4000, the program would limit the time to 10 minutes, based on the absolute limit you placed on the time of 600 seconds. Of course, the other station should be aware of your extend string. If this string comes in while you are not recording a message, it will be ignored. FLATLOG Use this parameter by itself to indicate that you want the sta- tion log to be kept in a "flat" file format. In this case, flat means that the data is in fixed columns. This might be useful for someone that wanted to process the log from a program and didn't want to deal with the "comma delimited" format that is the default. SNOW Some of the older CGA cards would produce snow on the screen when direct video writes were done. If you see snow on your screen, try to insert the snow directive in your simp.ini file. BIOS If you have a "near compatible" PC and the display isn't func- tioning correctly, try to use the bios method of writing data to the screen. It is fairly slow, but if that is all you have, it's better than nothing. Insert the bios directive in your simp.ini if you are still having trouble with snow. Don't have both active at the same 23 time. Include either snow or bios; or don't put anything. WARN- ING: if you use the bios option, ANSI graphics won't be displayed properly. NOMOUSE If you have a mouse, you will see a scrollbar to the right of the receiving (top) screen. If you find that having a mouse causes you problems, insert the nomouse directive to cause the program to treat you as if you didn't have a mouse. QUIET If you don't like the annoying startup screen telling you what you are running and who's sweat gave it to you, insert the quiet directive in your init file. DDMMYY Just in case someone wants to use this program in Europe or wherever else they use the day-month-year format, instead of the month-day-year used here, they can put this directive in their startup file and the program will generate the date October 31, 1993, as 31/10/93. YYMMDD This format is also included for completeness. It is left to the reader to determine what it means. (Hint: read the previous para- graph) LOGFILE This directive specifies the name of the station log. The default is station.log. Example: LOGFILE k4gvo.log BUTTON This directive is used to define one of a set of buttons that can be used to send commands to your tnc. Multiple BUTTON vari- ables may be defined and when the dispbut function is executed, a window will be displayed with a button for representing each of the BUTTON variables encountered in the initial file. The format of the BUTTON variable line is: BUTTON <label> <string> 24 Where <label> is the 1-8 character label assigned to button and the <string> is the character string that will be sent to the tnc when the button is pressed. Here is a sample set of BUTTON variables. BUTTON Amtor ^camtor^m BUTTON Cw ^cmorse^mmspeed 20^m BUTTON Pac_vhf ^cpacket^mvhf on^mhbaud 1200^m BUTTON Pac_hf ^cpacket^mvhf off^mhbaud 300^m BUTTON Amtor ^camtor^m When you execute the dispbut function, a window with 5 but- tons will be displayed. Select one or press the escape key to close the window without executing anything. 4.3 Color Configuration If you want to change the color scheme used by SimpTerm, you may use the config function. A number of foreground/background color combinations will be presented on the screen with a number identifying each one. A menu will also appear with a number of options. Select one of the window options to change the colors for that window by moving to the option with your up/down arrow keys and press return. You will be prompted for a number repre- senting the color you want to use. The other options on the menu let you save the color scheme that you have selected permanently or discard the changes or just use the new colors during the current session. Permanent screen colors are saved in the simp.cfg file. Distributed with SimpTerm is a simp.cfg suitable for a color mon- itor and a mono version, simpmono.cfg. If you want to use the mono version, just copy simpmono.cfg to simp.cfg. 4.4 Command line options The SimpTerm command line looks like: simp -init initfile -mid number -com comparamstring -word -V - quiet -cap cfile Where: quiet tells the program not to display the introductory screen. See the QUIET directive for more details. word causes displayed data in a window to wrap on a word boundry. V display the version number. cfile start the program with capture on and write to cfile 25 initfile is the name of a file to be used as the initialization file containing the key definitions and other customization pa- rameters. The default file name is "simp.ini". number is the line number of the middle of the screen. This is used to define the location of "split" between the transmit and receive windows. Default is 12. See the MID discussion elsewhere. comparamstring is the communications port parameter string. This specification overrides the COM init file option. The comparamstring parameter is in the form: comn,baud,wordsize,parity,stopbits,[base],[irq] Where: comn is the com port number, 1, 2, 3 or 4. This also can be specified as COM1, COM2, COM3 or COM4. baud is the baud rate. Must be one of, 300, 1200, 2400, 4800 or 9600. wordsize is either 7 or 8. parity is one of the following: N, O, E, M, S. stopbits is either 1 or 2. This is almost always 1. base is the base address of the COM port. This can be expressed as a c language hex number such as 0x03e8 or a decimal number like 123. irq is the interrupt number used by the COM port. This can be expressed as a c language hex number such as 0x0a or a decimal number like 13. The following settings are the most common. If you don't know for sure what to set them to, try these. <comn>,<baud>,7,E,1 <comn>,<baud>,8,N,1 and maybe <comn>,<baud>,7,O,1 The <comn> and <baud> depend on your computer hardware configuration and your tnc interface speed. You may use spaces instead of commas to separate the COM fields. If you do, you must enclose the entire field in quotes, such as: simp -com "COM1 4800 8 N 1" If you have both a COM option line in your init file and a command line com option then the command line option will be used. This way the command line can be used to override the init file if desired. 26 5 CD-ROM support This version of SimpTerm supports a lookup function that can be used to find calls in the FCC database. Both the QRZ and AmSoft CD-ROMs are supported. To use this feature you will need to include a line in your .ini file that looks like: QRZ d: or AMSOFT d: Where d: is the drive and optionally path to the database. For the July 1995 QRZ CD on CD-ROM drive G: you would use: QRZ G: For the September 1995 AmSoft CD on CD-ROM drive G: you would use: AMSOFT G: The lookup function will attempt to find an entry matching the call that is displayed at column 2 of the status bar in a CD- ROM database. The call displayed on the status bar was either as a result of clicking on the first letter of the call with the left mouse button or from invoking the getcall function. Use of this function requires that either the QRZ or AMSOFT parameter be used to specify the path to the CD-ROM drive and the CD present. 6 Mouse usage Most of this information is covered elsewhere, so if you need more information, check the index. The mouse can be disabled with the NOMOUSE parameter in the .ini file. Use this feature if SimpTerm erroneously senses that a mouse is attached or use of the mouse interfers with the operation. Clicking on a call in the receive window will select that call and place it near the left edge of the status bar. Operations using the active call such as invoking the lookup function or sending a string with the use this selected call. If you are using scroll bars on the windows, moving the mouse cursor to either the arrow at the top of the window or the bottom of the window and clicking the left button will cause the screen to scroll one line up or down. If the left button is clicked in the region below the thumb or slide bar the window is scrolled down a page and if the button is clicked in the region above the thumb the window is scrolled up one page. By moving the mouse cursor to 27 the thumb and pressing and holding the mouse button, the thumb can be dragged up or down, scrolling the window as it is dragged. Note that when the screen is displaying scrolled data, incoming data is not displayed. To see the incoming data be sure to scroll back down to the bottom or most recently displayed page. The pull-down menu can be displayed by pressing the middle button on a 3 button mouse. Many 2 button mice can emulate a middle button by pressing and releasing both buttons at the same time. Be sure to close the menu with the escape key when you are finished. 7 Pull-down menu The pull-down menu is accessed via the menu function. To use it you must have menu assigned to a function key. The middle button on a 3 button mouse will also bring up the pull-down menu. If you have used pull-down or drop-down menus before, you shouldn't have any trouble using this one. While the menu is being displayed you will see incoming data from the serial port, but you can't enter anything into the transmit buffer. To close the menu, press the Escape key. This also is used to close a sub-menu and return you to the drop-down menu. If you have both the main menu and a sub-menu displayed, you must press the Escape key twice to return to normal operation. You may also use the mouse to select from the menu items. 8 Station logbook The station logging screen allows you to enter a number of possibly helpful items. The first two fields will be filled in for you as they are the current date and time. The cursor will be positioned at the third field, but if you want to change the previous fields, just press the CTRL-TAB key. A list of the editing keys is available by pressing the F1 key while the logging data form is displayed. The fields and their sizes is as follows: Field Name Size Starting position in log file DATE 6 1 TIME 5 7 CALL 11 12 NAME 20 23 QTH 39 43 MY RST 7 82 HIS RST 5 89 MODE 10 94 28 COMMENTS 48 104 FREQUENCY 7 152 POWER 4 159 QSL 4 163 OTHER 12 167 ENDTIME 4 179 Which looks like about a 182 character record in the flatfile mode. I hope all of these fields are self-explanatory. The OTHER field is just an additional field that can be used to put things I didn't think of. If you elect not to use the flatfile mode your file will be in this format "103193","0532","k4gvo","Jim","Fayetteville, GA", "599","599","","10.109","100","","","","0650" Of course, it will be all on one line. This format is called "comma delimited" by *base and others of its ilk. This format may be imported to many of the database managers and spread- sheets available on DOS. If you don't like the layout, drop me a note. 9 Selective calling feature Here is part of a typical init file that will support the selective calling feature. !KEY_F10 togsel RSELCAL k4gvo K4GVO W4LYBZW k4gvozw ENDCAL ZCZC zczc NNNN nnnn ALLCAL ALLSTAT SELMAXT 240 seconds EXTEND MXLEN 600 SELREPLY \rx\r^o^o^o^o^o^ode k4gvo %D ^m^d If, in the body of a message being recorded, the string "MXLEN" is found, the time limit will be bumped up to 10 minutes. Note that the "seconds" field on the SELMAXT option line is really a comment and not a specification. The following line WON'T set the time to 2 minutes. SELMAXT 2 minutes 10 License I'm not going to bother with the usual nonsense about responsibil- ity and guarantees. If you're foolish enough to use a free package 29 with something that you think is critical enough that you might be tempted to sue someone if it screws up, you deserve what you might get. CAVEAT EMPTOR! I hope I spelled that right. My last Latin course was before my first FORTRAN II course. Am I telling my age? I guess I didn't mention that this program is almost free. Might even be freeware, but since freeware is a registered trademark, I understand, I won't call it that. If you use this program and feel it is of any value, please drop something in the next Salvation Army kettle you see. If that activity offends you for any reason, please just do something nice for someone that you wouldn't normally do. Like buy your secretary lunch the next time she screws up royally instead of reaming her out. You can use it, change it, abuse it, distribute it, charge for it or most anything else you want to do with it, except if you charge more than a reasonable copying charge for it, you must tell whoever you sold it to that they could have gotten it for nothing if they had just looked around. You may distribute it in any form, as long as this file is included in its original form. You may add as many files as you wish. If you want source, drop me a note and we'll discuss it. I'll probably eventually turn it out into the public domain, but I'd be too embarrassed to do so with it now. 11 In Case of Trouble Problem: You hook up the TNC and it won't talk to you. Solution: Check the com port parameters. If you are absolutely sure that they are right, try turning the TNC off and then back on. If you see the restart message on the screen, then you've probably got the flow control set wrong or an open wire in your RS-232 cable. Set the flow control to none and restart SimpTerm. If other terminal programs see to work, but SimpTerm doesn't, it is usually the flow control. If you don't see anything when you power-cycle the TNC, then you still might have a flow control problem or a com port setting problem. Be real sure that you have selected the right com port. Problem: You hook up the TNC and it prints garbage or a foreign language. Solution: This is usually caused by either an incorrect parity setting or an incorrect speed setting. If you see what look like words, but 30 half or so of the letters are wrong, it's probably the wrong parity. If it is total garbage, change the baud rate. 12 Error messages I hope they are few and perfectly understandable. I haven't com- piled a complete list, but here are a few you may encounter during the initialization phase. HELP line has no file name The HELP line must have a valid file name as the first parameter. LOGFILE line has no file name The LOGFILE line must have a valid file name as the first param- eter. PRELOAD has no file name The PRELOAD line must have a valid file name as the first pa- rameter. MID has no value The MID line must have a valid non-zero, non-blank value as the first parameter. Key table corrupt This is an internal error, it should never appear unless memory gets overwritten. Line nn, Invalid key name <keyname> SimpTerm can't identify the key name on the line, number nn. Check your spelling. Malloc failed SimpTerm ran out of memory. Number of lines, nnn exceeds max, mmm The maximum number of continuation lines has been exceeded. Port definition in error, line nnn There is something wrong with the COM port definition on line nnn. Be sure it looks like the examples given above. 31 Port init failed nn The attempt to initialize the com port failed with an error of nn. ERROR (some message) Messages of this type will be returned from the CD-ROM database access. If the message mentions MALLOC, then you probably ran out of memory. Try to use the CDSWAP parameter in your .ini file. If the message involves a file access error, open, read, etc. then check your QRZ or AMSOFT parameters to be sure the drive/path is correct. If the message concerns the "list" processing then you may have run out of memory. In that case try the CDSWAP pa- rameter. This is also true if you get the "ERROR not loaded" message. If you receive an error message that isn't mentioned above it may be an internal error and one that "shouldn't" ever happen, but did. In that case, please write me for assistance. Describe what you were doing at the time, and what brand of TNC you are using. Anything else that you can thing of would be helpful too. 13 Final notes I hope that you find this program easy and enjoyable to use. I wrote it while I was traveling with a T1000SE (8086) laptop (no hard drive), a PK-232 and a IC-730. I didn't really like to use a simple terminal program and felt the big gun programs, just were too clumsy for portable use. I've made a few enhancements to that original program and hope that you will find it acceptable. I suspect that you aren't going to find a cheaper product. This manual was typeset with LATEX. I will be offering a hard- copy of this manual on 8.5 x 11, 3 hole punched paper ready for your 3 ring binder in the near future at what amounts to repro- duction and mailing costs. If you are interested please drop me a note with a sase. If you like SimpTerm. Tell others about it. If you don't like it, please tell me why. If you don't like it and tell others that it isn't any good, then we all lose. You lose, 'cause I just might be able to make it what you wanted, if I only knew, others lose 'cause they might find something in it for them that you weren't interested in and I lose, 'cause my feelings have been hurt, so PLEASE if you want to complain, fire it my direction. I can't promise I can make it your personal rose garden, but I will try to fix any problems or deficiencies that might show up. 32 The documentation is slowly improving, but not quite as good as I would like to have it. I sure had fun with the spell checker. It wanted to make rtty into ratty and amtor into actor. Wonder if it knows something I don't? 14 Bugs I think I have fixed all that have been reported. I'm not happy with the editor in the macro function, but I'm rapidly running out of memory to make enhancements. I don't want to convert to a 32 bit format because I want to be able to continue to support the old platforms. The com configuration menu is only usable with a mouse. There isn't a keyboard interface. 15 Futures Clean up the code so I'm not embarrassed to distribute it. I'd like to add a more robust station logging function or maybe multitask with the command processor so one could run their fa- vorite logging program at the same time with out having to use DV or something similar. I'm working on a Linux version of SimpTerm as well as a Windows version. The Linux version is handicaped by the lack of a decent toolkit. I don't want to use Motif 'cause they want money for it and it doesn't make sense for me to give something away only to help line the pockets of someone less generous. The Windows version was stuck for months trying to find a bug. I find Windows a very hard environment to program in unless you work on it constantly. There is so much to remember that if you are away from it for a while you almost have to start again. 33 Index active call, 8, 11, 27 copying, 30 ALLCAL, 22 CTRL, 6 ALT, 6 ampersand, 9 database, 29 AmSoft, 12, 27 date and time display, 19 auto, 10, 13 dates and times in strings, 7 autoexec.bat, 20 day, 8 AUTOTIME, 13, 20 DAYTIME, 18 DDMMYY, 24 backslash, 9 DEBUG, 19 backslash character, 7 default, 16 backspace, 15 DEL_EQ_BKSP, 18 backspace key, 18 delete key, 18 base address, 26 DesqView, 18 baud rate, 26 dispbut, 10, 25 bauddown, 10, 12 display, 5 baudup, 10, 12 dos, 10 binary data, 11, 15 dos, entering, 12 BINARYCAP, 11 BINARYLOAD, 15 echo, 5 bios, 23 end, 15 bugs, 33 END key, 15 button, 24 ENDCAL, 22 environment variable, TZ, 20 call letters, 12, 27 Error messages, 31 calls, incoming, 11 Europe, 24 capture, 11, 25 exclamation, 15 CD, 12, 27 EXTEND, 23 CD-ROM, 12, 19, 27 CD-ROM support, 27 file, color configuration, 25 CDSWAP, 19 files, assigning to function keys, color configuration, 25 9 color, changing, 4 flatfile, 29 color, configuration, 25 FLATLOG, 23 COM port, 16, 26 flow control, 17 command line options, 25 function key, 4, 15 comment lines, 16 functions, assigning to keys, comments, 16 10 confcom, 10, 15 functions, list, 10 config, 10, 25 continuation, 9 getcall, 10 control character, 9 GMT, 20, 21 control characters, 7, 21 HELP, 17 34 help, 10 quiet, 25 help function, 11, 17 quit, 10, 15 hour, 8 rback, 10, 12 initial file, 5 rback1, 10, 12 initialization file, 4, 25, 26 receive, 5 irq, 26 reset, 10 RESLCAL, 21 keyboard, 33 return character, 7 Keyboard assignments, 5 rforward, 10, 12 keyboard macros, 8 rforward1, 10, 12 keybrcl, 10, 14 rlarger, 11, 12 rsmaller, 11, 12 License, 29 linefeed character, 7 savebuf, 11 log, 23, 33 scroll bar, disabling, 19 log file, 24 scroll bars, 27 logbook, 28 scrollbar, 24 LOGFILE, 24 scrolling, 12, 19 logit, 10, 11 SCROLLLINES, 19 lookup, 12, 27 selcal, 20 selective calling, 20, 29 macro, 10, 12, 13 SELFILE, 20 menu, 4, 10, 12 SELMAXT, 22 MID, 18, 25, 26 SELREPLY, 21, 22 minute, 8 SENDKEY, 14, 15 monochome, 25 SHIFT, 6 month, 8 simp.cfg, 25 mouse, 24, 33 simp.ini, 23 Mouse usage, 11, 27, 28 size of transmit window, 26 multi-tasking, 18 SNOW, 23 MYCALL, 4, 6, 8 source, 30 NODV, 18 special formatting characters, NOMOUSE, 27 21 NOSCROLLBAR, 19 startup screen, 24 notes, 32 stationslog,t11,a23,t24,u28s, 5, 11 parity, 26 status line, 5 PK-232, 21 stop, 15 POSTLOAD, 19 pound sign, 16 tab character, 7 PRELOAD, 18 TIMELINE, 19 pull-down menu, 11, 28 tkeybuf,t11,o14gcap, 11 QRZ, 12, 27 togsel, 11 Quick start, 4 transmit, 5 35 Transmit window, 5 transparent data, 11, 15 trouble, 30 TZ, 20 upload, 11, 15 video, 23 window size, specifying, 18 wrap, 25 xback, 11, 12 xback1, 11, 12 xforward, 11, 12 xforward1, 11, 12 year, 8 YYMMDD, 24 36